home *** CD-ROM | disk | FTP | other *** search
/ BCI NET 2 / BCI NET 2.iso / archives / programming / c / gcc263-doc.lha / gnu / man / man1 / ar.1 next >
Encoding:
Text File  |  1994-12-19  |  12.0 KB  |  331 lines
  1.  
  2.  
  3.  
  4. ar(1)                 GNU Development Tools                 ar(1)
  5.  
  6.  
  7. NNAAMMEE
  8.        ar - create, modify, and extract from archives.
  9.  
  10.  
  11. SSYYNNOOPPSSIISS
  12.        aarr [--]_{_d_m_p_q_r_t_x_}_[_a_b_c_i_l_o_s_u_v_V_] [_m_e_m_b_e_r_n_a_m_e] _a_r_c_h_i_v_e _f_i_l_e_s...
  13.  
  14.  
  15. DDEESSCCRRIIPPTTIIOONN
  16.        The GNU aarr program creates, modifies,  and  extracts  from
  17.        archives.   An  _a_r_c_h_i_v_e is a single file holding a collec-
  18.        tion of other files in a structure that makes it  possible
  19.        to  retrieve the original individual files (called _m_e_m_b_e_r_s
  20.        of the archive).
  21.  
  22.        The original files' contents, mode  (permissions),  times-
  23.        tamp,  owner,  and group are preserved in the archive, and
  24.        may be reconstituted on extraction.
  25.  
  26.        GNU aarr can maintain archives whose members have  names  of
  27.        any  length; however, depending on how aarr is configured on
  28.        your system, a limit on member-name length may be  imposed
  29.        (for  compatibility  with  archive formats maintained with
  30.        other tools).  If it exists, the limit is often 15 charac-
  31.        ters  (typical  of formats related to a.out) or 16 charac-
  32.        ters (typical of formats related to coff).
  33.  
  34.        aarr is considered a binary utility because archives of this
  35.        sort  are  most  often  used as _l_i_b_r_a_r_i_e_s holding commonly
  36.        needed subroutines.
  37.  
  38.        aarr will create an index to the symbols defined in relocat-
  39.        able  object  modules  in the archive when you specify the
  40.        modifier `ss'.  Once created, this index is updated in  the
  41.        archive  whenever  aarr makes a change to its contents (save
  42.        for the `qq' update operation).  An archive  with  such  an
  43.        index  speeds  up  linking to the library, and allows rou-
  44.        tines in the library to call each other without regard  to
  45.        their placement in the archive.
  46.  
  47.        You may use `nnmm --ss' or `nnmm ----pprriinntt--aarrmmaapp' to list this in-
  48.        dex table.  If an archive lacks the table, another form of
  49.        aarr called rraannlliibb can be used to add just the table.
  50.  
  51.        aarr  insists  on  at  least  two  arguments to execute: one
  52.        keyletter specifying the _o_p_e_r_a_t_i_o_n (optionally accompanied
  53.        by other keyletters specifying _m_o_d_i_f_i_e_r_s), and the archive
  54.        name to act on.
  55.  
  56.        Most operations can also accept further  _f_i_l_e_s  arguments,
  57.        specifying particular files to operate on.
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64. cygnus support           5 November 1991                        1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ar(1)                 GNU Development Tools                 ar(1)
  71.  
  72.  
  73. OOPPTTIIOONNSS
  74.        GNU aarr allows you to mix the operation code _p and modifier
  75.        flags _m_o_d in any order, within the first command-line  ar-
  76.        gument.
  77.  
  78.        If you wish, you may begin the first command-line argument
  79.        with a dash.
  80.  
  81.        The _p keyletter specifies what operation  to  execute;  it
  82.        may be any of the following, but you must specify only one
  83.        of them:
  84.  
  85.  
  86.        dd      _D_e_l_e_t_e modules from the archive.  Specify the names
  87.               of  modules  to be deleted as _f_i_l_e_s; the archive is
  88.               untouched if you specify no files to delete.
  89.  
  90.               If you specify the `vv' modifier, aarr will list  each
  91.               module as it is deleted.
  92.  
  93.  
  94.        mm      Use this operation to _m_o_v_e members in an archive.
  95.  
  96.               The  ordering  of  members in an archive can make a
  97.               difference in how programs are linked using the li-
  98.               brary, if a symbol is defined in more than one mem-
  99.               ber.
  100.  
  101.               If no modifiers are used with mm,  any  members  you
  102.               name in the _f_i_l_e_s arguments are moved to the _e_n_d of
  103.               the archive; you can use the `aa', `bb', or `ii' modi-
  104.               fiers to move them to a specified place instead.
  105.  
  106.  
  107.        pp      _P_r_i_n_t  the specified members of the archive, to the
  108.               standard output file.  If the `vv' modifier is spec-
  109.               ified, show the member name before copying its con-
  110.               tents to standard output.
  111.  
  112.               If you specify no  _f_i_l_e_s,  all  the  files  in  the
  113.               archive are printed.
  114.  
  115.  
  116.        qq      _Q_u_i_c_k  _a_p_p_e_n_d;  add  _f_i_l_e_s  to  the end of _a_r_c_h_i_v_e,
  117.               without checking for replacement.
  118.  
  119.               The modifiers `aa', `bb', and `ii' do _n_o_t affect  this
  120.               operation; new members are always placed at the end
  121.               of the archive.
  122.  
  123.               The modifier `vv' makes aarr list each file as  it  is
  124.               appended.
  125.  
  126.               Since  the  point  of  this operation is speed, the
  127.  
  128.  
  129.  
  130. cygnus support           5 November 1991                        2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ar(1)                 GNU Development Tools                 ar(1)
  137.  
  138.  
  139.               archive's symbol table index is not  updated,  even
  140.               if it already existed; you can use `aarr ss' or rraannlliibb
  141.               explicitly to update the symbol table index.
  142.  
  143.  
  144.        rr      Insert _f_i_l_e_s into _a_r_c_h_i_v_e (with _r_e_p_l_a_c_e_m_e_n_t).  This
  145.               operation  differs  from `qq' in that any previously
  146.               existing members are deleted if their  names  match
  147.               those being added.
  148.  
  149.               If  one  of the files named in _f_i_l_e_s doesn't exist,
  150.               aarr displays an error  message,  and  leaves  undis-
  151.               turbed any existing members of the archive matching
  152.               that name.
  153.  
  154.               By default, new members are added at the end of the
  155.               file;  but  you  may  use one of the modifiers `aa',
  156.               `bb', or `ii' to request placement relative  to  some
  157.               existing member.
  158.  
  159.               The modifier `vv' used with this operation elicits a
  160.               line of output for each file inserted,  along  with
  161.               one  of  the letters `aa' or `rr' to indicate whether
  162.               the file was appended (no old  member  deleted)  or
  163.               replaced.
  164.  
  165.  
  166.        tt      Display a _t_a_b_l_e listing the contents of _a_r_c_h_i_v_e, or
  167.               those of the files listed in _f_i_l_e_s that are present
  168.               in  the  archive.  Normally only the member name is
  169.               shown; if you also want to see the  modes  (permis-
  170.               sions),  timestamp, owner, group, and size, you can
  171.               request that by also specifying the `vv' modifier.
  172.  
  173.               If you do not specify any _f_i_l_e_s, all files  in  the
  174.               archive are listed.
  175.  
  176.               If  there  is more than one file with the same name
  177.               (say, `ffiiee') in an archive (say `bb..aa'), `aarr  tt  bb..aa
  178.               ffiiee' will list only the first instance; to see them
  179.               all, you must ask for a  complete  listing--in  our
  180.               example, `aarr tt bb..aa'.
  181.  
  182.  
  183.        xx      _E_x_t_r_a_c_t  members  (named  _f_i_l_e_s)  from the archive.
  184.               You can use the `vv' modifier with  this  operation,
  185.               to  request  that  aarr list each name as it extracts
  186.               it.
  187.  
  188.               If you do not specify any _f_i_l_e_s, all files  in  the
  189.               archive are extracted.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196. cygnus support           5 November 1991                        3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. ar(1)                 GNU Development Tools                 ar(1)
  203.  
  204.  
  205.        A  number  of modifiers (_m_o_d) may immediately follow the _p
  206.        keyletter, to specify variations on an operation's  behav-
  207.        ior:
  208.  
  209.  
  210.        aa      Add  new  files  _a_f_t_e_r  an  existing  member of the
  211.               archive.  If you use the modifier aa, the name of an
  212.               existing archive member must be present as the _m_e_m_-
  213.               _b_e_r_n_a_m_e argument, before the _a_r_c_h_i_v_e specification.
  214.  
  215.  
  216.        bb      Add  new  files  _b_e_f_o_r_e  an  existing member of the
  217.               archive.  If you use the modifier bb, the name of an
  218.               existing archive member must be present as the _m_e_m_-
  219.               _b_e_r_n_a_m_e argument, before the _a_r_c_h_i_v_e specification.
  220.               (same as `ii').
  221.  
  222.  
  223.        cc      _C_r_e_a_t_e  the  archive.  The specified _a_r_c_h_i_v_e is al-
  224.               ways created if it didn't exist, when  you  request
  225.               an  update.   But  a  warning  is issued unless you
  226.               specify in advance that you expect to create it, by
  227.               using this modifier.
  228.  
  229.  
  230.        ii      Insert  new  files _b_e_f_o_r_e an existing member of the
  231.               archive.  If you use the modifier ii, the name of an
  232.               existing archive member must be present as the _m_e_m_-
  233.               _b_e_r_n_a_m_e argument, before the _a_r_c_h_i_v_e specification.
  234.               (same as `bb').
  235.  
  236.  
  237.        ll      This modifier is accepted but not used.
  238.  
  239.  
  240.        oo      Preserve  the  _o_r_i_g_i_n_a_l  dates  of members when ex-
  241.               tracting them.  If you do not specify this  modifi-
  242.               er,  files  extracted  from  the  archive  will  be
  243.               stamped with the time of extraction.
  244.  
  245.  
  246.        ss      Write an object-file index into the archive, or up-
  247.               date  an  existing  one, even if no other change is
  248.               made to the archive.  You  may  use  this  modifier
  249.               flag  either with any operation, or alone.  Running
  250.               `aarr ss' on  an  archive  is  equivalent  to  running
  251.               `rraannlliibb' on it.
  252.  
  253.  
  254.        uu      Normally, aarr rr... inserts all files listed into the
  255.               archive.  If you would like to insert _o_n_l_y those of
  256.               the  files  you  list  that are newer than existing
  257.               members of the same names, use this modifier.   The
  258.               `uu'  modifier is allowed only for the operation `rr'
  259.  
  260.  
  261.  
  262. cygnus support           5 November 1991                        4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. ar(1)                 GNU Development Tools                 ar(1)
  269.  
  270.  
  271.               (replace).  In particular, the combination `qquu'  is
  272.               not  allowed,  since  checking the timestamps would
  273.               lose any speed advantage from the operation `qq'.
  274.  
  275.  
  276.        vv      This modifier requests the _v_e_r_b_o_s_e  version  of  an
  277.               operation.   Many operations display additional in-
  278.               formation, such as filenames  processed,  when  the
  279.               modifier `vv' is appended.
  280.  
  281.  
  282.        VV      This modifier shows the version number of aarr.
  283.  
  284.  
  285.  
  286.  
  287. SSEEEE AALLSSOO
  288.        `bbiinnuuttiillss' entry in iinnffoo; _T_h_e _G_N_U _B_i_n_a_r_y _U_t_i_l_i_t_i_e_s, Roland
  289.        H. Pesch (October 1991).  nnmm(11), rraannlliibb((1)).
  290.  
  291.  
  292. CCOOPPYYIINNGG
  293.        Copyright (c) 1991 Free Software Foundation, Inc.
  294.  
  295.        Permission is granted  to  make  and  distribute  verbatim
  296.        copies  of  this  manual provided the copyright notice and
  297.        this permission notice are preserved on all copies.
  298.  
  299.        Permission is granted to copy and distribute modified ver-
  300.        sions  of  this  manual  under the conditions for verbatim
  301.        copying, provided that the entire resulting  derived  work
  302.        is  distributed  under  the  terms  of a permission notice
  303.        identical to this one.
  304.  
  305.        Permission is granted to copy and distribute  translations
  306.        of this manual into another language, under the above con-
  307.        ditions for modified versions, except that this permission
  308.        notice  may  be  included  in translations approved by the
  309.        Free Software Foundation instead of in  the  original  En-
  310.        glish.
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328. cygnus support           5 November 1991                        5
  329.  
  330.  
  331.